home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / Imaging & Layout / Adjusting the Active Border < prev    next >
Encoding:
Text File  |  1995-07-10  |  5.2 KB  |  116 lines  |  [TEXT/ttxt]

  1. OpenDoc™ Recipes
  2.  
  3. Adjusting the Active Border
  4. by The OpenDoc Design Team
  5. April 19, 1995
  6.  
  7.  
  8. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  9. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  10. Mac and OpenDoc are trademarks of Apple Computer, Inc.
  11.  
  12.  
  13. About the Active Frame Border
  14.  
  15. The display of the active frame border is managed by OpenDoc. Neither the active part nor its containing part need to display the active border; OpenDoc itself does that. All the active part needs to do to get the active border is to acquire the Selection focus, and relinquishing the focus will remove the border.
  16.  
  17. Even though the containing part doesn’t have to display the active border of an embedded frame, it does have to deal with the border to some extent. There are two things the containing part must do:
  18.  
  19. • Adjust the active border’s shape. This amounts to clipping the shape where it is obscured by intrinsic content or embedded frames in the containing part.
  20.  
  21. • Ensure that the active border is not overwritten by intrinsic content or embedded parts it obscures. This requires that the containing part clip the active border shape from the obscured parts. See the Clipping Embedded Facets recipe for information on how to do that.
  22.  
  23. Adjusting the Border Shape
  24.  
  25. When an embedded frame acquires the selection focus, or a frame that already has the focus has its FrameShape changed, OpenDoc will calculate a new active border shape, and then ask the frame’s containing part to adjust it. OpenDoc will call AdjustBorderShape() on the containing part, passing the shape to be adjusted, and the facet it is associated with.
  26.  
  27. Adjusting the active border shape is a straightforward process. Just clip out all the portions that are obscured by the containing part’s intrinsic content or embedded frames. Do not clip the shape to the containing part’s clip shape; OpenDoc will do that.
  28.  
  29. About Reference Counts
  30.  
  31. The AdjustBorderShape() method is considered a source for the returned shape. It may be creating a new shape, which will have to be released later. For that reason, if all your part does is return the shape parameter, it must make sure to inflate the reference count first. Remember the, shape param may be released by the calling code after the method exits, so you can't rely on that reference to keep the shape alive.
  32.  
  33. Clipping Obscured Content and Parts
  34.  
  35. After the containing part has adjusted the active border shape, it should store the adjusted shape in a variable or field. When the stored shape is non-null, the part should make sure that intrinsic content or embedded frames are clipped so they do not overwrite the active border.
  36.  
  37. When the active border is moved to a different frame, OpenDoc will notify the containing part by calling AdjustBorderShape with a value of kODNULL for the shape. The containing part can then un-clip obscured content and embedded frames. If the containing part receives several AdjustBorderShape calls in a row that all have non-null shapes, it should use the union of all those shapes for clipping its content and embedded frames. This is because there may be more than one facet on the active frame embedded in the same containing part.
  38.  
  39. Sample Code
  40.  
  41. Note that this sample code does not deal with intrinsic content, but only with embedded parts. See the Clipping Embedded Facets recipe for an example of how to generalize this code to deal with intrinsic content.
  42.  
  43. #include "Facet.xh"
  44. #include "FacetItr.xh"
  45. #include "Frame.xh"
  46. #include "Shape.xh"
  47. #include "Trnsform.xh"
  48.  
  49.  
  50. ODShape* CMyPart::AdjustBorderShape(Environment *ev,
  51.         ODFacet* embeddedFacet,
  52.         ODShape* shape)
  53. {
  54.     ODFacet* dispFacet = embeddedFacet->GetContainingFacet(ev);    
  55.     ODCanvas* biasCanvas = dispFacet->GetCanvas(ev);
  56.  
  57.     if ( shape == kODNULL )
  58.     {
  59.         fActiveBorderShape->Release(ev);
  60.         fActiveBorderShape = kODNULL;
  61.         this->ClipEmbeddedFacets(ev, dispFacet);
  62.         return kODNULL;
  63.     }
  64.  
  65.     ODTransform* xform = kODNULL;
  66.     ODShape* tShape = kODNULL;
  67.     ODShape* adjusted = shape->Copy(ev);
  68.     
  69.     xform = embeddedFacet->AcquireExternalTransform(ev, biasCanvas);
  70.     adjusted->Transform(ev, xform);        // now in cont frame coords (mine)
  71.     xform->Release(ev);
  72.     
  73.     ODFrame* dispFrame = dispFacet->AcquireFrame(ev);
  74.  ODShape* dispShape = dispFrame->AcquireUsedShape(ev, biasCanvas);
  75.     adjusted->Intersect(ev, dispShape);
  76.     dispShape->Release(ev);
  77.     
  78.     ODFacet* facet = kODNULL;
  79.     ODBoolean above = kODFalse;
  80.     ODFacetIterator* facets = dispFacet->CreateFacetIterator(ev, kODChildrenOnly, kODBackToFront);
  81.     for (facet = facets->First(ev);
  82.             facets->IsNotComplete(ev);
  83.             facet = facets->Next(ev))
  84.     {
  85.         if ( above )
  86.         {
  87.    ODFrame* frame = facet->AcquireFrame(ev);
  88.             tShape = ODCopyAndRelease(ev, frame->AcquireUsedShape(ev, biasCanvas));
  89.             xform = facet->AcquireExternalTransform(ev, biasCanvas);
  90.             tShape->Transform(ev, xform);
  91.             adjusted->Subtract(ev, tShape);
  92.             tShape->Release(ev);
  93.             xform->Release(ev);
  94.    frame->Release(ev):
  95.         }
  96.         else
  97.         {
  98.             above = ( facet == embeddedFacet );
  99.         }
  100.     }
  101.  
  102.     if ( fActiveBorderShape == kODNULL )
  103.         fActiveBorderShape = adjusted->Copy(ev);
  104.     else
  105.         fActiveBorderShape->Union(ev, adjusted);
  106.  
  107.     xform = embeddedFacet->AcquireExternalTransform(ev, biasCanvas);
  108.     adjusted->InverseTransform(ev, xform);        // now in embedded frame coords
  109.     xform->Release(ev);
  110.     
  111.     this->ClipEmbeddedFacets(ev, dispFacet);
  112.     return adjusted;
  113. }
  114.  
  115.